Pose2Idle by Riskbreak
======================

Turns a Brio .livepose OR an Anamnesis .pose into an FFXIV animation mod
(.pmp) - no Blender, no manual steps.

FIRST RUN
  No game files are included - they belong to Square Enix, and you already
  have them. Press "Get game files" once and the tool copies what it needs
  out of your own installation: every race's idle, all six C-Pose slots and
  every skeleton, around 130 files. It only reads; nothing in the game is
  changed and nothing is downloaded. You never have to do it again.
  A Setup window explains this on first launch, and the button stays green
  until the files are there.

QUICK START
  1. Double-click Pose2Idle.cmd
  1b. Press "Get game files" if you have not already
  2. Pick your .livepose or .pose - the output name fills in to match
  2b. Pick your Race / Gender - the skeleton, animation and game path all
     fill in automatically
  3. Choose an output name, press "Build .pmp"
  4. Import the .pmp into Penumbra as its own mod, zone or relog, done

The pose is applied as an offset over the existing animation, so the
character keeps the vanilla motion's natural sway and the loop stays
seamless - the same way Brio layers a live pose in gpose.

SMOOTH TRANSITIONS
  Sitting down (or moving into any numbered pose) plays a separate "start"
  animation that ends in the game's own stance, so a custom pose can appear
  to snap into place at the last moment.
  "Blend into the pose" (Advanced, on by default) rebuilds that
  animation as well, easing the pose in so it lands exactly where the looping
  pose begins. The mod then contains both files.
  Each frame is blended from where the original animation already is toward
  where the pose ends up, rather than the pose being layered on top of a
  moving animation - layering fights the motion and reads as a wobble.
  The animations that play on the way in are rebuilt:
    event_base/event_base_ground_start.pap  the sit-down itself
    event_base/event_base_chair_start.pap
    emote/*_start.pap                       the move into a numbered pose
  All of them are made to finish on exactly the pose that was built, so
  nothing steps or shifts on arrival.
  A build never touches another /cpose slot. Sitting down from standing does
  pass through the game's default sit (emote/sit.pap, emote/jmn.pap) for a
  moment; those files are /cpose slot 0, so they are deliberately left alone. Each frame travels from where the character starts to where
  the pose ends up.
  The sit-down clip is shared by every sit of that kind for that race, so a
  mod that rebuilds it affects the initial sit into any of those poses.
  The seconds box sets how fast that journey is: 0 is instant and the game's
  blending carries them in, 0.3 is a brisk settle, 1.0 is slow and graceful.
  If you fetched game files before this existed, press "Get game files"
  again - the transition animations were not downloaded then.

SHARED ANIMATIONS
  Square never authored a separate idle for Highlanders - the game falls back
  to the Midlander stance, so there is no c0301/c0401 idle in VFXEditor to
  find. Pick "Highlander M/F" and the tool handles it: it targets the
  Midlander game path while still using the Highlander skeleton, and the note
  beside the dropdown tells you which files to supply.

GET GAME FILES
  The "Get game files" button reads your FFXIV installation directly and
  pulls every race's idle, all six pose slots and every skeleton into
  gamefiles\ - roughly 130 files in one press, instead of exporting them one
  at a time. It only reads; nothing in the game is touched.
  It looks for the install itself; if it cannot find it, point the picker at
  the folder containing game\sqpack.
  Command line: runtime\python.exe app\Pose2Idle.py --fetch "C:\path\to\FINAL FANTASY XIV"

POSE TYPES AND C-POSE SLOTS
  The Type dropdown chooses between Standing, Ground Sit and Chair Sit; the
  C-Pose Slot below it then lists that type's base animation and the /cpose
  variants:
      Standing    resident/idle.pap        emote/poseNN_loop.pap
      Ground Sit  emote/jmn.pap            emote/j_poseNN_loop.pap
      Chair Sit   emote/sit.pap            emote/s_poseNN_loop.pap
  Races do not all have the same number of sitting poses. "Get game files"
  records what each race actually has, and the slot list then shows only
  those. Before that first fetch, every possible slot is listed.
  Only the Loop of each pose is offered - the Start is the short move into
  it and transitions cleanly on its own.

RACES
  Miqo'te F (c0801) and Au Ra F (c1401) ship with this tool - pick them from
  the dropdown and everything fills in.
  For any other race, choose it in the dropdown, then point "Source .pap" and
  "Skeleton .sklb" at raw extracts for that race:
      VFXEditor > Pap tab > Game Items > Character > <race> > General > Idle
      chara/human/cXXXX/skeleton/base/b0001/skl_cXXXXb0001.sklb
  Export them RAW (VFXEditor or TexTools "Extract Raw"), and drop them in
  gamefiles\ named  cXXXX_idle.pap  and  cXXXX_skele.sklb  to have the
  dropdown pick them up automatically from then on.
  The pap's model id is checked against the selected race, so a mismatched
  pairing is refused rather than silently building something wrong.

  Bone names are shared across races so poses transfer, but proportions are
  not: a pose authored on a Viera will place arms differently on a Lalafell.

OTHER ANIMATIONS (cposes, sitting)
  Open "Advanced" to choose a different animation inside the pap and set the
  game path it replaces. Both are filled in for the standing idle by default.

WHAT'S IN THIS FOLDER
  Pose2Idle.cmd         the launcher. Two lines of plain text - open it
                        in Notepad if you like. It starts the bundled
                        Python on app\Pose2Idle.py and nothing else.
  app\                  the program (plain Python, readable)
  runtime\              bundled Python (nothing to install)
  XATHavokInterop.exe   Havok converter from the XAT project (BSD-3-Clause,
                        github.com/Etheirys/XAT) - does the compression
  gamefiles\            empty until you press "Get game files"
  custom skeletons\     appears only if you point the skeleton line
                        at a mod - holds what was taken out of it

POSE FILE TYPES
  .livepose (Brio)     offsets over the playing animation - applied as-is
  .pose (Anamnesis /   absolute pose - converted to offsets automatically.
         Ktisis)       Face/hair bones are skipped (the body animation doesn't
                       carry them).
  For both formats, skirt/weapon physics bones are left to the game so they
  don't fight the physics sim - tick "Enable Skirt Posing" under Advanced to
  use the arrangement saved in the pose file instead.

POSITION EDITS
  Almost all of a pose is rotations, but a bone can also be DRAGGED
  somewhere in Anamnesis / Ktisis / Brio. Those edits are detected - a bone
  whose stored position no longer matches the skeleton's own geometry - and
  carried into the animation automatically; the log lists which bones were
  moved. If nearly every bone looks moved, the pose was made for a body
  with different proportions (usually another race): the tool says so and
  skips position edits rather than deforming the skeleton.

IVCS / YAS BONES
  IVCS and YAS add extra posing bones (iv_*, ya_*) that the game's own
  skeleton does not have. Whether they are used now depends on the
  skeleton a build runs against, not on their names:
    - vanilla skeleton: skipped, because the bones are not there
    - custom skeleton:  posed, because they are
  The log says which happened and how many. See CUSTOM SKELETONS.

MODEL TRANSFORM (Brio)
  Brio's Model Transform moves or turns the whole actor rather than any bone,
  and is saved into the pose file as a difference from the natural stance.
  It is ignored by default - tick "Model transform (Brio)" under Advanced to
  carry it into the animation. The rotation turns the whole body (pivoting at
  the actor's origin on the floor) and the position shifts it; the size part
  is never carried over. "Snap feet to ground" still re-levels the height
  afterwards, so turn that off to keep a deliberate float or sink.

FACIAL EXPRESSIONS
  The Expression dropdown holds one of the game's 28 named expressions
  (Smile, Sad, Wink...) while the idle plays. The face is its own
  animation, so the chosen expression replaces the neutral face and is
  built for EVERY face type your race has - you never need to know which
  face number your character uses.
  "Face posing" (Advanced) uses the face saved in your .pose file instead
  - eyes, brows, mouth, exactly as you posed them. It greys out the
  dropdown: it is one or the other, never both.
  "Blinking" (Advanced, on by default) controls whether the character
  still blinks over the held face. Winks read better with it off.
  Face animations are new to "Get game files" - if you fetched with an
  older version, press it again once.

SLIDING, CLIPPING, BREATHING (the sway sliders)
  Vanilla idle motion is a bundle: breathing AND a weight-shift that moves
  the whole skeleton. Each slider = how much vanilla motion that area keeps.

  PRESETS                  spine/arms/balance/everything else/tail
    Breathing     55/0/0/0/100   a gentle breath in the chest and head and a
                                 normally moving tail, with the lower body
                                 completely still
    Natural       55/0/100/0/100 DEFAULT and recommended - Breathing plus the
                                 balance shift of a standing body
    Statue        0/0/0/0/0      no motion at all, tail included
                                 (verified: zero in the file)
    Experimental  100/100/100/10/100
                                 adds full arm drift and a little root motion

  Anything still moving with Statue is engine-side - cloth and hair
  physics, head look-at, blinking. No animation file controls those.

BALANCE (new in 8.1, replaces "Legs & hips")
  Nobody stands perfectly still from the waist down. The game gives every
  race a small weight shift while idling, and it is the difference between
  a pose that lives and a mannequin.

  The shift itself is one bone, n_hara, which slides the whole skeleton -
  4 mm on Miqo'te F, 14 mm on Roegadyn M. The hip and leg bones barely
  rotate; what little they do is the counter-motion that keeps the feet
  planted while the body travels over them. The two only mean anything
  together, which is why the old "Legs & hips" slider always skated: it
  moved the legs without the body they were balancing against.

  Balance drives all of them as one unit, and the feet are then re-pinned
  against YOUR pose - the game's counter-motion was choreographed for its
  own stance, so under a pose it no longer cancels. Measured across all
  16 races, feet travel under 0.01 mm at full Balance. The game's own
  idles measure 0.12 to 2.55 mm, so this is steadier than vanilla.

  Safe to raise. It cannot make the feet slide.

KNEE STIFFNESS
  How hard the knees work to hold the feet down while the body shifts.
  Only does anything when Balance is above zero.

  100% (default) pins the feet exactly, and already bends the knee LESS
  than the game does - 0.6 deg against vanilla's 2.5 deg. The pinning is
  what holds the knee still, so turning this DOWN bends it more, not less,
  and lets the feet skate. Leave it at 100 unless the knees bother you.

  Raising it stiffens the knee further, but the leg can then no longer
  absorb the whole shift and the feet begin to travel:

    100%   0.6 deg of knee bend    0.14 mm of foot travel
    125%   0.35 deg                2.2 mm      <- the stillest a knee gets
    150%   0.63 deg                4.4 mm

  Past 125% the knee bends MORE again and the feet keep sliding, so there
  is no reason to go higher.

TAIL (Miqo'te, Au Ra and Hrothgar)
  The tail has its own slider, at full motion by default. The game animates
  it far more than anything else - measured peaks of 20 deg on Miqo'te F and
  42 deg on Au Ra F, against roughly 2 deg of chest sway - so holding it
  still is very visible.
  It is safe to leave at 100: the tail touches nothing, so it cannot cause
  sliding or clipping the way the leg and arm sliders can. Lower it only if
  a pose tucks the tail somewhere deliberate and you want it to stay there.

  This slider alone goes past 100, up to 500, which widens the arc beyond
  what Square animated. 100 is the game's own swing, 150 is noticeably
  livelier, 200 is showy. The effect compounds down the chain, so on
  Au Ra F the tip measures 42 deg at 100, 62 at 150, 83 at 200, 125 at 300
  and 166 at 400 - the base moves a little, the tip moves a great deal.

  Past roughly 400 the tip passes half a turn, and a rotation of more than
  180 deg is the same as a shorter one the other way round, so it folds
  back instead of opening further. Au Ra F has by far the largest tail
  animation in the game and is the only one that reaches this - 400 is her
  practical ceiling. Races with smaller tail motion stay sensible all the
  way to 500. Anything that high is worth a look in game first: the tail
  can sweep through the legs, a chair or a skirt.
  Earlier versions held the tail still along with everything else. Setting
  the slider to 0 reproduces that exactly.

REBUILDING WITH DIFFERENT SLIDERS
  Each build names the mod after the pose plus its slider values and a short
  fingerprint, e.g.  Idle - mypose [S100 A0 B100 E0 T100] 4f458a
  (S spine, A arms, B balance, E everything else, T tail)
  Knee stiffness adds K only when it is not the default, e.g. ... T100 K125]
  So every rebuild imports as its OWN mod in Penumbra instead of silently
  colliding with the previous one - and the name tells you which settings
  you are looking at.
  If the fingerprint in the log changes but the game looks identical, the
  old mod is still the active one: delete it in Penumbra, import the new
  one, and zone or relog (the game caches animations).

WHOLE-BODY LEAN (.pose root bones)
  Anamnesis poses often store a body lean in the root bones (n_hara sits
  directly above j_kosi). Child bones are authored relative to that tilt, so
  the lean must be applied or the pose comes out leaning the WRONG way, much
  harder than intended. The "Whole-body lean" box (on by default) applies it
  and reproduces the source pose exactly. Turn it off only if a pose was
  captured on a slope or facing oddly.

FLOATING / HEIGHT (Snap feet to ground)
  Posing is rotational, so bending a hip or knee lifts the feet - but the
  game pins the character's ROOT to the ground and never looks at where the
  feet ended up, so the pose appears to hover. (In gpose you fix this by
  dragging the actor down, but that is a world position the game owns, so it
  cannot survive into an animation.)
  "Snap feet to ground" (on by default) measures the lowest foot and lowers
  the body by the same amount. Measured drops: a light pose needed 0.3 cm,
  a crossed-leg stance needed 12.1 cm.
  Use "nudge cm" for a manual offset on top: negative sinks her into the
  ground, positive floats her. Uncheck the box to keep the pose's own height.

EVERY LAUNCH
  The pose file and output boxes always start blank, so a previous build can
  never be overwritten by accident. Everything else - source pap, skeleton,
  sliders, game path - is remembered. Hover any blue (i) badge for an explanation of that setting.

BONE SIZES
  Poses can resize bones as well as rotate them. "Enable Scaling Support"
  (Advanced, off by default) carries those sizes into the animation.
  Only the bones the pose resized change. A size multiplies down the chain in
  the game's skeleton, so scaling an upper arm would otherwise swell the
  forearm, hand and every finger with it - the direct children are corrected
  so the enlargement stops where it should.
  Equipment helpers (n_hhiji and similar) and physics bones are ignored; they
  carry small incidental values rather than deliberate resizes.
  Tail bones are an exception: they are named like equipment
  helpers but a resized tail is deliberate, so it is carried over. Size and
  swing are independent - a tail can be resized and still move normally.

SETTINGS BUTTON
  Always save to the same folder   new mods go to the folder you last
                                   saved into, named after the pose, rather
                                   than landing beside the pose file
  Hide the Source .pap line     both fill themselves in from the race and
  Hide the Skeleton .sklb line  slot, so they can be hidden if never touched

  Beside the Type dropdown, "snap feet: on / off" shows whether feet are being
  pulled down to floor level. Good for standing idles; often worth turning off
  for sitting poses, where the feet may be up on a chair or tucked under.

ANTIVIRUS
  This release scans clean: 0 detections out of 63 engines on
  VirusTotal. Check the hash published with the download against the
  file you got, and you know you have exactly what I built.
  Earlier versions shipped a small Pose2Idle.exe that did nothing but
  start the bundled Python. A handful of scanners flagged it - never
  naming a virus, only guessing from the shape of the file, because a
  small program whose job is to launch a scripting runtime looks like
  a malware loader and also looks like every portable Python app ever
  written. That launcher is gone and the flags went with it.
  You can check the rest yourself: the whole program is readable
  Python in app\Pose2Idle.py. It uses the standard library only, and
  it contains no networking code at all - it cannot download or send
  anything, to me or to anybody.

CUSTOM SKELETONS (part 1 - YAS only for now)
  A pose can only move a bone that exists in the skeleton it was built
  against. The game's own skeleton has a fixed set, so anything a body
  mod adds - and any tail on a race that has none - is out of reach
  until you build against that skeleton instead.

  Point the "Skeleton .sklb / mod" line at YAS and those bones become
  posable. You can hand it the mod file directly; it takes the right
  race out for you.

  Where to get it:
      https://heliosphere.app/mod/yab
      Use the variant dropdown and select "Skeleton".

  What YAS adds, per race: 62 IVCS bones, 5 physics bones, and - for
  Highlander F, Roegadyn F and Viera F - a tail, which those races do
  not have at all in the base game. Female races only.

  Show the skeleton line first: Settings > untick "Hide the Skeleton
  .sklb line". The round arrow beside Browse puts you back on the
  game's own skeleton whenever you want.

  ANYONE WHO USES THE MOD NEEDS THE SAME SKELETON INSTALLED. Those
  bones will not exist on a character without it.

  Only YAS is supported for now. Other custom skeletons may work, but
  nothing else has been tested and no promises are made until the
  rough edges here are found and fixed.

BORROW TAIL ANIMATION
  Square only animated a tail for Miqo'te, Au Ra and Hrothgar. Every
  other race either holds its tail still or has no tail bones, so a
  tail mod on them hangs dead no matter what the Tail slider says -
  the slider scales movement, and there is none to scale.

  Advanced > "Borrow tail animation" copies the sway from a race that
  has one. It is offered only to races that need it, and greyed out
  for the six that already sway.

  Only the movement is copied, so the tail still hangs where your pose
  and skeleton put it. The Tail slider then scales it like any other
  motion, so 300% works on a borrowed tail too. The sway lands on
  whichever slot you are building, and stretches to fit its length.

  Races with no tail bones need a custom skeleton first - see above.

NOTES
  - Builds self-check: the finished animation is decompressed and compared
    against your pose; output is refused if it deviates.
  - Personal use only. Don't redistribute mods built from other creators'
    work, and don't reupload this folder.

CREDITS
  Pose2Idle by Riskbreak - Discord: Riskbreak
  Havok conversion by XAT (Asgard / Etheirys, BSD 3-Clause).
  Penumbra, VFXEditor, Brio, Anamnesis, Dalamud by their respective authors.
  FINAL FANTASY XIV is the property of Square Enix; this tool is unaffiliated.
